---
category: '@threlte/xr'
title: '<XR>'
order: 0
type: 'component'
componentSignature:
  {
    props:
      [
        {
          name: 'foveation',
          type: 'number',
          default: '1',
          required: false,
          description: 'Enables foveated rendering. 0 represents no foveation, full resolution. 1 represents maximum foveation, with the edges rendered at a lower resolution.'
        },
        {
          name: 'frameRate',
          type: 'number',
          required: false,
          description: 'The target framerate for the XRSystem. Recommended range is 72-120. Default is unset and left to the device. Smaller rates give more CPU headroom at the cost of responsiveness. If your experience cannot effectively reach the target framerate, it will be subject to frame reprojection which will halve the effective framerate. Choose a conservative estimate that balances responsiveness and headroom based on your experience.'
        },
        {
          name: 'referenceSpace',
          type: 'string',
          required: false,
          default: "'local-floor'",
          description: 'Type of WebXR reference space to use.'
        }
      ],
    events:
      [
        {
          name: 'sessionstart',
          payload: 'THREE.Event & { target: XRSession }',
          description: 'Fired as an XRSession is requested.'
        },
        {
          name: 'sessionend',
          payload: 'THREE.Event & { target: XRSession }',
          description: 'Fired after an XRSession is terminated.'
        },
        {
          name: 'visibilitychange',
          payload: 'THREE.Event & { target: XRSession }',
          description: 'Fired when an XRSession is hidden or unfocused.'
        },
        {
          name: 'inputsourceschange',
          payload: 'THREE.Event & { target: XRSession }',
          description: 'Fired when available inputsources change.'
        }
      ]
  }
---

The `<XR>` component prepares your scene for a WebXR session. It sets up context that is provided by the [`useXR`](/docs/reference/xr/use-xr) hook.

## Usage

```svelte
<script>
  import { XR } from '@threlte/xr'
  import { Text } from '@threlte/extras'
</script>

<XR>
  <Text
    position={[0, 1.6, -1]}
    text="I have entered another realm!"
  />
</XR>
```

<Tip type="warning">
  The `<XR>` component will set the [`<Canvas>`](/docs/reference/core/canvas) property `renderMode="always"` when the user enters an XR session, due to being incompatible with `on-demand` or `manual`. It will set the original value once the session has ended.
</Tip>

Any children of the `<XR>` component will not mount until the user enters an immersive session. This is useful for adding controllers, hands, or entire scenes that should only start when the user has begun their session.

## Fallback

XR sessions have to be requested actively and you might want to show contents to the user before they have entered an immersive session. You can use the `fallback` snippet to show a fallback scene to the user.

```svelte
<script>
  import { T } from '@threlte/core'
  import { XR, Controller } from '@threlte/xr'
  import { OrbitControls } from '@threlte/extras'
  import Scene from './Scene.svelte'
</script>

<Scene />

<XR>
  <Controller left>
  <Controller right>

  {#snippet fallback()}
    <T.PerspectiveCamera makeDefault position.z={5}>
      <OrbitControls />
    </T.PerspectiveCamera>
  {/snippet}
</XR>
```
